<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Themes  Reference</title>
    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
    <link rel="stylesheet" type="text/css" href="css/highlight.css" />
    <meta charset='utf-8'>
    <script src="js/jquery.min.js" defer></script>
    <script src="js/jazzy.js" defer></script>
    
    <script src="js/lunr.min.js" defer></script>
    <script src="js/typeahead.jquery.js" defer></script>
    <script src="js/jazzy.search.js" defer></script>
  </head>
  <body>
    <a name="//apple_ref/swift/Section/Themes" class="dashAnchor"></a>
    <a title="Themes  Reference"></a>
    <header>
      <div class="content-wrapper">
        <p><a href="index.html">ThemeKit 1.4.0 Docs</a></p>
        <p class="header-right"><a href="https://github.com/luckymarmot/ThemeKit"><img src="img/gh.png"/>View on GitHub</a></p>
        <p class="header-right"><a href="dash-feed://http%3A%2F%2Fthemekit.nunogrilo.com%2Fdocsets%2FThemeKit.xml"><img src="img/dash.png"/>Install in Dash</a></p>
        <p class="header-right">
          <form role="search" action="search.json">
            <input type="text" placeholder="Search documentation" data-typeahead>
          </form>
        </p>
      </div>
    </header>
    <div class="content-wrapper">
      <p id="breadcrumbs">
        <a href="index.html">ThemeKit Reference</a>
        <img id="carat" src="img/carat.png" />
        Themes  Reference
      </p>
    </div>
    <div class="content-wrapper">
      <nav class="sidebar">
        <ul class="nav-groups">
          <li class="nav-group-name">
            <a href="ThemeKit.html">ThemeKit</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Classes/ThemeManager.html">ThemeManager</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/ThemeManager/WindowThemePolicy.html">– WindowThemePolicy</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Notification.html">Notification</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Notification/Name.html">– Name</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Themes.html">Themes</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Protocols/Theme.html">Theme</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/LightTheme.html">LightTheme</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/DarkTheme.html">DarkTheme</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/SystemTheme.html">SystemTheme</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/UserTheme.html">UserTheme</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Theme%20Assets.html">Theme Assets</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Classes/ThemeColor.html">ThemeColor</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/ThemeGradient.html">ThemeGradient</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/ThemeImage.html">ThemeImage</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Extensions.html">Extensions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Extensions/NSWindow.html">NSWindow</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/NSColor.html">NSColor</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
      <article class="main-content">
        <section>
          <section class="section">
            <h1>Themes</h1>
            
          </section>
          <section class="section task-group-section">
            <div class="task-group">
              <ul>
                <li class="item">
                  <div>
                    <code>
                    <a name="/c:@M@ThemeKit@objc(pl)TKTheme"></a>
                    <a name="//apple_ref/swift/Protocol/Theme" class="dashAnchor"></a>
                    <a class="token" href="#/c:@M@ThemeKit@objc(pl)TKTheme">Theme</a>
                    </code>
                  </div>
                  <div class="height-container">
                    <div class="pointer-container"></div>
                    <section class="section">
                      <div class="pointer"></div>
                      <div class="abstract">
                        <p>Theme protocol: the base of all themes.</p>

<p><em>ThemeKit</em> makes available, without any further coding:</p>

<ul>
<li>a <code><a href="Classes/LightTheme.html">LightTheme</a></code> (the default macOS theme)</li>
<li>a <code><a href="Classes/DarkTheme.html">DarkTheme</a></code> (the dark macOS theme, using <code>NSAppearanceNameVibrantDark</code>)</li>
<li>a <code><a href="Classes/SystemTheme.html">SystemTheme</a></code> (which dynamically resolve to either <code><a href="Classes/LightTheme.html">LightTheme</a></code> or `DarkTheme 
depending on the macOS preference at <strong>System Preferences &gt; General &gt; Appearance</strong>)</li>
</ul>

<p>You can choose wheter or not to use these, and you can also implement your custom
themes by:</p>

<ul>
<li>implementing native <code>Theme</code> classes conforming to this protocol and <code>NSObject</code></li>
<li>provide user themes (<code><a href="Classes/UserTheme.html">UserTheme</a></code>) with <code>.theme</code> files</li>
</ul>

<p>Please check the provided <em>Demo.app</em> project for sample implementations of both.</p>

                        <a href="Protocols/Theme.html" class="slightly-smaller">See more</a>
                      </div>
                      <div class="declaration">
                        <h4>Declaration</h4>
                        <div class="language">
                          <p class="aside-title">Swift</p>
                          <pre class="highlight swift"><code><span class="kd">@objc</span><span class="p">(</span><span class="kt">TKTheme</span><span class="p">)</span>
<span class="kd">public</span> <span class="kd">protocol</span> <span class="kt">Theme</span> <span class="p">:</span> <span class="kt">NSObjectProtocol</span></code></pre>

                        </div>
                      </div>
                      <div class="slightly-smaller">
                        <a href="https://github.com/luckymarmot/ThemeKit/blob/master/Sources/Theme.swift#L31-L61">Show on GitHub</a>
                      </div>
                    </section>
                  </div>
                </li>
                <li class="item">
                  <div>
                    <code>
                    <a name="/c:@M@ThemeKit@objc(cs)TKLightTheme"></a>
                    <a name="//apple_ref/swift/Class/LightTheme" class="dashAnchor"></a>
                    <a class="token" href="#/c:@M@ThemeKit@objc(cs)TKLightTheme">LightTheme</a>
                    </code>
                  </div>
                  <div class="height-container">
                    <div class="pointer-container"></div>
                    <section class="section">
                      <div class="pointer"></div>
                      <div class="abstract">
                        <p>Light theme (default).</p>

                        <a href="Classes/LightTheme.html" class="slightly-smaller">See more</a>
                      </div>
                      <div class="declaration">
                        <h4>Declaration</h4>
                        <div class="language">
                          <p class="aside-title">Swift</p>
                          <pre class="highlight swift"><code><span class="kd">@objc</span><span class="p">(</span><span class="kt">TKLightTheme</span><span class="p">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="kt">LightTheme</span> <span class="p">:</span> <span class="kt">NSObject</span><span class="p">,</span> <span class="kt"><a href="Protocols/Theme.html">Theme</a></span></code></pre>

                        </div>
                      </div>
                      <div class="slightly-smaller">
                        <a href="https://github.com/luckymarmot/ThemeKit/blob/master/Sources/LightTheme.swift#L13-L39">Show on GitHub</a>
                      </div>
                    </section>
                  </div>
                </li>
                <li class="item">
                  <div>
                    <code>
                    <a name="/c:@M@ThemeKit@objc(cs)TKDarkTheme"></a>
                    <a name="//apple_ref/swift/Class/DarkTheme" class="dashAnchor"></a>
                    <a class="token" href="#/c:@M@ThemeKit@objc(cs)TKDarkTheme">DarkTheme</a>
                    </code>
                  </div>
                  <div class="height-container">
                    <div class="pointer-container"></div>
                    <section class="section">
                      <div class="pointer"></div>
                      <div class="abstract">
                        <p>Dark theme.</p>

                        <a href="Classes/DarkTheme.html" class="slightly-smaller">See more</a>
                      </div>
                      <div class="declaration">
                        <h4>Declaration</h4>
                        <div class="language">
                          <p class="aside-title">Swift</p>
                          <pre class="highlight swift"><code><span class="kd">@objc</span><span class="p">(</span><span class="kt">TKDarkTheme</span><span class="p">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="kt">DarkTheme</span> <span class="p">:</span> <span class="kt">NSObject</span><span class="p">,</span> <span class="kt"><a href="Protocols/Theme.html">Theme</a></span></code></pre>

                        </div>
                      </div>
                      <div class="slightly-smaller">
                        <a href="https://github.com/luckymarmot/ThemeKit/blob/master/Sources/DarkTheme.swift#L13-L39">Show on GitHub</a>
                      </div>
                    </section>
                  </div>
                </li>
                <li class="item">
                  <div>
                    <code>
                    <a name="/c:@M@ThemeKit@objc(cs)TKSystemTheme"></a>
                    <a name="//apple_ref/swift/Class/SystemTheme" class="dashAnchor"></a>
                    <a class="token" href="#/c:@M@ThemeKit@objc(cs)TKSystemTheme">SystemTheme</a>
                    </code>
                  </div>
                  <div class="height-container">
                    <div class="pointer-container"></div>
                    <section class="section">
                      <div class="pointer"></div>
                      <div class="abstract">
                        <p>System theme. </p>

<p>Will dynamically resolve to either <code><a href="Classes/ThemeManager.html#/c:@M@ThemeKit@objc(cs)TKThemeManager(cpy)lightTheme">ThemeManager.lightTheme</a></code> or <code><a href="Classes/ThemeManager.html#/c:@M@ThemeKit@objc(cs)TKThemeManager(cpy)darkTheme">ThemeManager.darkTheme</a></code>,
depending on the macOS preference at <strong>System Preferences &gt; General &gt; Appearance</strong>.</p>

                        <a href="Classes/SystemTheme.html" class="slightly-smaller">See more</a>
                      </div>
                      <div class="declaration">
                        <h4>Declaration</h4>
                        <div class="language">
                          <p class="aside-title">Swift</p>
                          <pre class="highlight swift"><code><span class="kd">@objc</span><span class="p">(</span><span class="kt">TKSystemTheme</span><span class="p">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="kt">SystemTheme</span> <span class="p">:</span> <span class="kt">NSObject</span><span class="p">,</span> <span class="kt"><a href="Protocols/Theme.html">Theme</a></span></code></pre>

                        </div>
                      </div>
                      <div class="slightly-smaller">
                        <a href="https://github.com/luckymarmot/ThemeKit/blob/master/Sources/SystemTheme.swift#L16-L65">Show on GitHub</a>
                      </div>
                    </section>
                  </div>
                </li>
                <li class="item">
                  <div>
                    <code>
                    <a name="/c:@M@ThemeKit@objc(cs)TKUserTheme"></a>
                    <a name="//apple_ref/swift/Class/UserTheme" class="dashAnchor"></a>
                    <a class="token" href="#/c:@M@ThemeKit@objc(cs)TKUserTheme">UserTheme</a>
                    </code>
                  </div>
                  <div class="height-container">
                    <div class="pointer-container"></div>
                    <section class="section">
                      <div class="pointer"></div>
                      <div class="abstract">
                        <p>A <code><a href="Protocols/Theme.html">Theme</a></code> class wrapping a user provided theme file (<code>.theme</code>).</p>

<p>To enable user themes, set theme folder on <code><a href="Classes/ThemeManager.html#/c:@M@ThemeKit@objc(cs)TKThemeManager(py)userThemesFolderURL">ThemeManager.userThemesFolderURL</a></code>.</p>

<p>Notes about <code>.theme</code> files:</p>

<ul>
<li>lines starting with <code>#</code> or <code>//</code> will be treated as comments, thus, ignored;</li>
<li>non-comment lines consists on simple variable/value assignments (eg, <code>variable = value</code>);</li>
<li><code>variable</code> name can contain characters <code>[a-zA-Z0-9_-.]+</code>;</li>
<li>custom variables can be specified (eg, <code>myBackgroundColor = ...</code>);</li>
<li>theming properties match the class methods of <code><a href="Classes/ThemeColor.html">ThemeColor</a></code>, <code><a href="Classes/ThemeGradient.html">ThemeGradient</a></code> and <code><a href="Classes/ThemeImage.html">ThemeImage</a></code> (eg, <code>labelColor</code>);</li>
<li>variables can be referenced by prefixing them with <code>$</code> (eg, <code>mainBorderColor = $commonBorderColor</code>);</li>
<li>colors are defined using <code>rgb(255, 255, 255)</code> or <code>rgba(255, 255, 255, 1.0)</code> (case insensitive);</li>
<li>gradients are defined using <code>linear-gradient(color1, color2)</code> (where colors are defined as above; case insensitive);</li>
<li>pattern images are defined using <code>pattern(named:xxxx)</code> (named images) or <code>pattern(file:../dddd/xxxx.yyy)</code> (filesystem images);</li>
<li>images are defined using <code>image(named:xxxx)</code> (named images) or <code>image(file:../dddd/xxxx.yyy)</code> (filesystem images);</li>
<li><code><a href="Classes/ThemeManager.html#/c:@M@ThemeKit@objc(cs)TKThemeManager(py)themes">ThemeManager.themes</a></code> property is automatically updated when there are changes on the user themes folder;</li>
<li>file changes are applied on-the-fly, if it corresponds to the currently applied theme.</li>
</ul>

<p>Example <code>.theme</code> file:</p>
<pre class="highlight ruby"><code><span class="sr">//</span> <span class="o">*************************</span> <span class="no">Theme</span> <span class="no">Info</span> <span class="o">*************************</span> <span class="sr">//</span>
<span class="n">displayName</span> <span class="o">=</span> <span class="no">My</span> <span class="no">Theme</span> <span class="mi">1</span>
<span class="n">identifier</span> <span class="o">=</span> <span class="n">com</span><span class="p">.</span><span class="nf">luckymarmot</span><span class="o">.</span><span class="no">ThemeKit</span><span class="o">.</span><span class="no">MyTheme1</span>
<span class="n">darkTheme</span> <span class="o">=</span> <span class="kp">true</span>

<span class="sr">//</span> <span class="o">*********************</span> <span class="no">Colors</span> <span class="o">&amp;</span> <span class="no">Gradients</span> <span class="o">*********************</span> <span class="sr">//</span>
<span class="c1"># define color for `ThemeColor.brandColor`</span>
<span class="n">brandColor</span> <span class="o">=</span> <span class="vg">$blue</span>
<span class="c1"># define a new color for `NSColor.labelColor` (overriding)</span>
<span class="n">labelColor</span> <span class="o">=</span> <span class="n">rgb</span><span class="p">(</span><span class="mi">11</span><span class="p">,</span> <span class="mi">220</span><span class="p">,</span> <span class="mi">111</span><span class="p">)</span>
<span class="c1"># define gradient for `ThemeGradient.brandGradient`</span>
<span class="n">brandGradient</span> <span class="o">=</span> <span class="n">linear</span><span class="o">-</span><span class="n">gradient</span><span class="p">(</span><span class="vg">$orange</span><span class="p">.</span><span class="nf">sky</span><span class="p">,</span> <span class="n">rgba</span><span class="p">(</span><span class="mi">200</span><span class="p">,</span> <span class="mi">140</span><span class="p">,</span> <span class="mi">60</span><span class="p">,</span> <span class="mf">1.0</span><span class="p">))</span>

<span class="sr">//</span> <span class="o">*********************</span> <span class="no">Images</span> <span class="o">&amp;</span> <span class="no">Patterns</span> <span class="o">**********************</span> <span class="sr">//</span>
<span class="c1"># define pattern image from named image "paper" for color `ThemeColor.contentBackgroundColor`</span>
<span class="n">contentBackgroundColor</span> <span class="o">=</span> <span class="n">pattern</span><span class="p">(</span><span class="n">named</span><span class="ss">:paper</span><span class="p">)</span>
<span class="c1"># define pattern image from filesystem (relative to user themes folder) for color `ThemeColor.bottomBackgroundColor`</span>
<span class="n">bottomBackgroundColor</span> <span class="o">=</span> <span class="n">pattern</span><span class="p">(</span><span class="n">file</span><span class="p">:</span><span class="o">..</span><span class="sr">/some/</span><span class="n">path</span><span class="o">/</span><span class="n">some</span><span class="o">-</span><span class="n">file</span><span class="p">.</span><span class="nf">png</span><span class="p">)</span>
<span class="c1"># use named image "apple"</span>
<span class="n">namedImage</span> <span class="o">=</span> <span class="n">image</span><span class="p">(</span><span class="n">named</span><span class="ss">:apple</span><span class="p">)</span>
<span class="c1"># use image from filesystem (relative to user themes folder)</span>
<span class="n">fileImage</span> <span class="o">=</span> <span class="n">image</span><span class="p">(</span><span class="n">file</span><span class="p">:</span><span class="o">..</span><span class="sr">/some/</span><span class="n">path</span><span class="o">/</span><span class="n">some</span><span class="o">-</span><span class="n">file</span><span class="p">.</span><span class="nf">jpg</span><span class="p">)</span>

<span class="sr">//</span> <span class="o">***********************</span> <span class="no">Common</span> <span class="no">Colors</span> <span class="o">************************</span> <span class="sr">//</span>
<span class="n">blue</span> <span class="o">=</span> <span class="n">rgb</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">170</span><span class="p">,</span> <span class="mi">255</span><span class="p">)</span>
<span class="n">orange</span><span class="p">.</span><span class="nf">sky</span> <span class="o">=</span> <span class="n">rgb</span><span class="p">(</span><span class="mi">160</span><span class="p">,</span> <span class="mi">90</span><span class="p">,</span> <span class="mi">45</span><span class="p">,</span> <span class="o">.</span><span class="mi">5</span><span class="p">)</span>

<span class="sr">//</span> <span class="o">**********************</span> <span class="no">Fallback</span> <span class="no">Assets</span> <span class="o">***********************</span> <span class="sr">//</span>
<span class="n">fallbackForegroundColor</span> <span class="o">=</span> <span class="n">rgb</span><span class="p">(</span><span class="mi">255</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">90</span><span class="p">,</span> <span class="mf">1.0</span><span class="p">)</span>
<span class="n">fallbackBackgroundColor</span> <span class="o">=</span> <span class="n">rgb</span><span class="p">(</span><span class="mi">255</span><span class="p">,</span> <span class="mi">200</span><span class="p">,</span> <span class="mi">190</span><span class="p">)</span>
<span class="n">fallbackGradient</span> <span class="o">=</span> <span class="n">linear</span><span class="o">-</span><span class="n">gradient</span><span class="p">(</span><span class="vg">$blue</span><span class="p">,</span> <span class="n">rgba</span><span class="p">(</span><span class="mi">200</span><span class="p">,</span> <span class="mi">140</span><span class="p">,</span> <span class="mi">60</span><span class="p">,</span> <span class="mf">1.0</span><span class="p">))</span>
</code></pre>

<p>With the exception of system overrided named colors (e.g., <code>labelColor</code>), which
defaults to the original system provided named color, unimplemented properties 
on theme file will default to <code>-fallbackForegroundColor</code>, <code>-fallbackBackgroundColor</code>,
<code>-fallbackGradient</code> and <code>-fallbackImage</code>, for foreground color, background color,
gradients and images, respectively.</p>

                        <a href="Classes/UserTheme.html" class="slightly-smaller">See more</a>
                      </div>
                      <div class="declaration">
                        <h4>Declaration</h4>
                        <div class="language">
                          <p class="aside-title">Swift</p>
                          <pre class="highlight swift"><code><span class="kd">@objc</span><span class="p">(</span><span class="kt">TKUserTheme</span><span class="p">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="kt">UserTheme</span> <span class="p">:</span> <span class="kt">NSObject</span><span class="p">,</span> <span class="kt"><a href="Protocols/Theme.html">Theme</a></span></code></pre>

                        </div>
                      </div>
                      <div class="slightly-smaller">
                        <a href="https://github.com/luckymarmot/ThemeKit/blob/master/Sources/UserTheme.swift#L76-L228">Show on GitHub</a>
                      </div>
                    </section>
                  </div>
                </li>
              </ul>
            </div>
          </section>
        </section>
        <section id="footer">
          <p>© 2016-2017 <a class="link" href="https://paw.cloud" target="_blank" rel="external">Paw</a> &amp; <a class="link" href="http://nunogrilo.com" target="_blank" rel="external">Nuno Grilo</a> under <a class="link" href="https://github.com/luckymarmot/ThemeKit/blob/master/LICENSE" target="_blank" rel="external">MIT License</a>.</p>
          <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.13.7</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
        </section>
      </article>
    </div>
  </body>
</div>
</html>
